Snapshot Testing for CLI / REPL Applications
This crate allows to:
- Create transcripts of interacting with a terminal, capturing both the output text and ANSI-compatible color info.
- Save these transcripts in the SVG format, so that they can be easily embedded as images into HTML / Markdown documents
- Parse transcripts from SVG
- Test that a parsed transcript actually corresponds to the terminal output (either as text or text + colors).
The primary use case is easy to create and maintain end-to-end tests for CLI / REPL apps. Such tests can be embedded into a readme file.
Usage
Add this to your Crate.toml
:
[]
= "0.2.0"
Example of usage:
use ;
use str;
let transcript = from_inputs?;
let mut writer = vec!;
// ^ Any `std::io::Write` implementation will do, such as a `File`.
new.render?;
println!;
Ok::
See more examples in the crate docs.
Snapshot examples
Here's an SVG snapshot of the rainbow
example
produced by this crate:
Here's a snapshot of the same example with the scrolling animation and window frame:
Limitations
- Terminal coloring only works with ANSI escape codes. (Since ANSI escape codes are supported even on Windows nowadays, this shouldn't be a significant problem.)
- ANSI escape sequences other than SGR ones are either dropped (in case of CSI sequences), or lead to an error.
- By default, the crate exposes APIs to perform capture via OS pipes.
Since the terminal is not emulated in this case, programs dependent on
isatty
checks or getting term size can produce different output than if launched in an actual shell (no coloring, no line wrapping etc.). - It is possible to capture output from a pseudo-terminal (PTY) using the
portable-pty
crate feature. However, since most escape sequences are dropped, this is still not a good option to capture complex outputs (e.g., ones moving cursor). - PTY support for Windows is shaky. It requires a somewhat recent Windows version (Windows 10 from October 2018 or newer), and may work incorrectly even for the recent versions.
Alternatives / similar tools
insta
is a generic snapshot testing library, which is amazing in general, but kind of too low-level for E2E CLI testing.rexpect
allows testing CLI / REPL applications by scripting interactions with them in tests. It works in Unix only.trybuild
snapshot-tests output of a particular program (the Rust compiler).- Tools like
termtosvg
and Asciinema allow recording terminal sessions and save them to SVG. The output of these tools is inherently dynamic (which, e.g., results in animated SVGs). This crate intentionally chooses a simpler static format, which makes snapshot testing easier.
License
Licensed under either of Apache License, Version 2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in term-transcript
by you, as defined in the Apache-2.0 license,
shall be dual licensed as above, without any additional terms or conditions.